/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007-2008 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.projects.toolbox_basics_project.web.gwt.form.bean;

import java.util.List;

import com.genia.toolbox.basics.exception.BundledException;
import com.genia.toolbox.projects.toolbox_basics_project.bean.ParameterHandler;
import com.genia.toolbox.projects.toolbox_basics_project.bean.PersistableApplicationParameter;
import com.genia.toolbox.web.gwt.basics.client.oracle.SimpleSuggestion;
import com.genia.toolbox.web.gwt.form.client.form.MutableItem;
import com.genia.toolbox.web.gwt.form.client.value.FormSimpleValue;

/**
 * handler to allow edition of parameters.
 * 
 * @param <TYPE>
 *          the type of the {@link PersistableApplicationParameter} handled by
 *          this object.
 */
public interface FormParameterHandler<TYPE>
    extends ParameterHandler<TYPE>
{

  /**
   * returns the {@link MutableItem} that allow editing of the current
   * parameter.
   * 
   * @param label
   *          the label for the given parameter
   * @param applicationParameter
   *          the parameter to generate the from
   * @return the {@link MutableItem} that allow editing of the current parameter
   * @throws BundledException
   *           if an error occured
   */
  public abstract MutableItem getItem(String label, PersistableApplicationParameter<TYPE> applicationParameter)
      throws BundledException;



  /**
   * returns the current value of the parameter given in argument.
   * 
   * @param applicationParameter
   *          the parameter to extract the current value from
   * @return the current value of the parameter given in argument
   * @throws BundledException
   *           if an error occured
   */
  public abstract FormSimpleValue getCurrentValue(PersistableApplicationParameter<TYPE> applicationParameter)
      throws BundledException;



  /**
   * set the current value of the parameter given in argument.
   * 
   * @param applicationParameter
   *          the parameter to set the current value from
   * @param formSimpleValue
   *          the new value of the parameter
   * @throws BundledException
   *           if an error occured
   */
  public abstract void setCurrentValue(PersistableApplicationParameter<TYPE> applicationParameter, FormSimpleValue formSimpleValue)
      throws BundledException;



  /**
   * get suggestions for the parameter given in argument.
   * 
   * @param applicationParameter
   *          the parameter to get the suggestions for
   * @param query
   *          the current value of the field
   * @param limit
   *          the maximum number of response
   * @return the list of suggestion for the field
   * @throws BundledException
   *           when an error occurred
   * @see com.genia.toolbox.web.gwt.form.server.provider.FormProvider#getSuggestions(String,
   *      java.lang.String, java.lang.String, int)
   */
  public abstract List<SimpleSuggestion> getSuggestions(PersistableApplicationParameter<TYPE> applicationParameter, String query, int limit)
      throws BundledException;



  /**
   * get the display string for a given value.
   * 
   * @param applicationParameter
   *          the parameter to get the suggestions for
   * @param value
   *          the current value of the field
   * @return the string to display for the given value
   * @throws BundledException
   *           when an error occurred
   */
  public abstract String getDisplayString(PersistableApplicationParameter<TYPE> applicationParameter, String value)
      throws BundledException;

}
